When a Choreography Diagram is initially created, it will create a default Choreography Task. It is possible to simply change this information as the starting point for your diagram, but for the purposes of this article we will create a choreography task from scratch – so select this default choreography task and delete it.

Components to be included in the Choreography Diagram are provided in the palette on the right hand side of the canvas. We initially want to start the diagram with a “Start Event”, a “Choreography Task” and a “Sequence Flow” to connect the two. This should then look like this....

The Properties view will show the details for the newly create Choreography Task, allowing you to change its name to something that reflects what it represents, e.g. “Submit Purchase Order”.

The next step is to establish the Participants that will be performing the interaction associated with the Choreography Task. As shown in the diagram, the Choreography Task has a short cut button (also available via its context menu) to add a participant.

When this button is pressed, it will add a new participant to the task, or if available, also present a list of existing participants that can be selected. The first participant added to the choreography task will be considered the 'initiating participant', which means it will send the message. If two messages are associated with the same choreography task (e.g. representing a request/response pattern), then the initiator sends the request, and the other participant would return the response. In general, only associate two messages with a choreography task if the associated 'operation' will only have the single response type. If it has multiple response types (e.g. one normal and one or more faults), then separate choreography tasks should be used – as will be seen later in the purchasing example.

When the participant band has been added to the choreography task, it can be selected to focus the Properties view on its properties. The name can then be changed to something more meaningful, for example Buyer. The following image shows the task after both participants have been added and their names changed.

Now that we have defined the choreography task to represent an interaction from the Buyer to the Seller, we now need to describe the message that will be passed between them.

As with adding participants, there is a short cut button (and context menu item) for adding a message, associated with the participant band that is sending the message. So in the image above, adding a message to the Buyer would define the request, as the Buyer is the initiator for this task (denoted by its white background).

As with the 'Add Participant' action, if there are existing message definitions, then these will be presented to the user to enable them to select a previously defined message. Otherwise a message icon will simply be added.

The user can now select this message 'envelope' to view its properties and set its name, e.g. “BuyRequest”.

However the BuyRequest name is only a logical name, it does not define the details of the message structure. This is ok when we are simply sketching the high level representation of a choreography, but to enable the choreography to represent concrete details, we need to associate the message with an item definition.

In the Properties view associated with the selected message there is an 'Item' field. This allows the user to select a previously defined message type (e.g. from an imported XSD schema), or if an appropriate entry does not exist, then we can press the 'Create New' button.

The 'Item Kind' field will always be 'Information', unless defining some abstract choreography describing how physical items are exchanged. The 'Data Type' field references the detailed message schema type. To set the field, press the 'Edit...' button and set the value:

NOTE: Currently this only enables a free format string value to be defined – but should bring up the import dialog and enable the user to select a specific type, creating the import entry on the fly if necessary.

Now that the message details have been provided, the diagram displays that information in place of the logical message name.

NOTE: Currently does not actively update after this information is set – or when the message name is changed (when no item definition set).